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Documents on the Web 


O ne year ago, we launched thiscolumn with an essay 
on project documentation. We followed up in 
September 1995 with some code sketches for imple¬ 
menting a hyperliterate documenting system for Visual- 
Works under Envy. 

Now the World Wide Web has taken the planet by 
storm. Thisisboth acrisisand an opportunity. Those who 
ignore theWeb risk ending up as road kill on theinfobahn. 
On the other hand, those who approach theWeb with a 
thoughtless, knee-jerk reaction arejust as likely to fail. 

The latter approach can significantly reduce produc¬ 
tivity. "MegaCorp's goal is to have all project documenta¬ 
tion available on the Web," sounds nice, until it is fol¬ 
lowed with "therefore, all programmers will immediately 
attend HTML trai ni ng, so they can create thei r documen¬ 
tation for the Web." This makes it very difficult to fulfill 
our first principle of hyperliterate programming: 

The documentation for a thing must be on the same 
conceptual /eve/ as that thing. 

The developers will have to "shift mental gears" to get 
out of Smalltalk mode and into HTML mode. Knuth's 
initial concept of literate programming required pro¬ 
grammers to learn and use a complex textual mark-up 
language which muddled their conceptual space. Even¬ 
tually, tools for LaTeX emerged, but literate programming 
never quite reached the masses, largely because of the 
cognitive dissonance between coding programs and cod¬ 
ing documentation. 

"No problem, we’ll invest in Web authoring tools to 
make the HTML part easy." This also kills productivity, 
which is now a victim of ignoring our second principleof 
hyperliterate programming: 

The documentation for a thing must constantly and 
accurately describe that thing. 

If developers are leaving Smalltalkto write Web pages, 
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no matter how good their Web authoring tools, neither 
their code nor their documentation is going to be as good 
as it would be if they combined the two activities in one 
environment. One or the other will suffer, and it is almost 
always the documentation that is not "constantly and 
accurately" describing the code. 

In reality, the only principle of hyperliterate program¬ 
ming that Web authoring partially fulfills isthe third one: 

The documentation for a thing must be accessible; by 
creators, their peers, reusers, re/i ewers, end-user docu- 
menters, and the merely curious 

But wait, who does Web authoring give improved ac¬ 
cess to? Certainly not the creator or their peers, who must 
now have both Smalltalk and a Web browser running in 
order to do their job. Probably not reusers, once they 
make the initial Web query and then need deeper access. 
Probably not all reviewers, some of whom will want de¬ 
tailed information from within Smalltalk. 

So, Web authoring provides increased access to end- 
user documenters and the merely curious, at the expense 
of the two usage roles most involved with development- 
creators and thei r peers! 

Finally, our fourth principle of hyperliterate program¬ 
ming states: 

The documentation for a thing must be measurable, 
quantitatively and especially qualitatively. 

Anyone who can type "du -s" in the root directory of a 
UNIX Web tree wi 11 get a gross measu re of the docu men- 
tation, but what will that tell us? Web authoring is inap¬ 
propriate for hyperliterate programming because it is 
file-based—you will need an entire new suite of tools to 
do quantitative and qualitative analysis. If you’ve got a 
perl guru in your group, that might work, but why not 
leverage the Smalltalk talent you’ve been carefully grow¬ 
ing? It’s unlikely that files of HTM L code will ever be mea¬ 
sured as part of a repository-centric metrics program. 

THEWEB IS AN EXPORTTARGET 

Just because we don’t believe "Web authoring” is appro¬ 
priate for hyperliterate Smalltalk development doesn’t 
mean wethinktheWeb useless. "Web authoring” means 
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the creation of Web documents by humans, which is great 
if you want to create a "cool site" or impress others with 
your HTML prowess, but it is at odds with the principles 
of hyperliterate programming, which require keeping 
documentation as close to the code as possible, in terms 
of granularity of concept, as well as physical location. 

The knee-jerk problems happen when some vice-pres¬ 
ident says "We gotta get on the Web!" and the ripple effect 
causes otherwise bright people to do stupid things, such 
as dictate that all Smalltalk documentation will be in 
HTML. 

Fortunately, HTML is easy to generate from your 
Smalltalk-resident documentation. If you followed the 
implementation sketch for Smalltalk hypertext we pre¬ 
sented in September 1995, you already have a good start. 

That implementation used a special emphasisfor Vis- 
ualWorks Text that allowed it to treat Smalltalk expres¬ 
sions specially This was but a small step from "real" 
hypertext. We have since extended so it has a notion of 
both an anchor, or visible text with human-meaningful 
presentation, and an action, which is a block of Smalltalk 
source code. To distinguish this, we call it a "clickAction 
Visual Works has been criticized for being divorced 
from platform capabilities, but its Text class provides an 
abstraction for styled text that is much more powerful 
than thoughtlessly abdicating all presentation to platform 
widgets. Text has an efficient tagged-character facility that 
allows you to associatearbitraryobjects with runsof char¬ 
acters Three common tag types are: 

• A simpleemphaslsSymbol, such as#bold or#italic, 

• a compound emphasis Array of other emphases, such 
as#( #bold #italic), 

•a parameterized emphasis Association between a 
Symbol and an arbitrary object. 

This last capability is used for things li ke colored text and 
different fonts or font sizes. 

We defined a new parameterized emphasis for Text 
that contains the Symbol #clickAction associated with 
Smalltalk source code for a block. We made changes to 
ParagraphEditor so that double-clicking one of these 
"clickActions" causes the block to be evaluated—instant 
hypertextITo enablethis, you need a"global method" that 
can discri mi nate clickActions: 

Object 

isClickAction 

"When used as an emphasis in a Text, do I function as 
a hyper link? Hardly!!" 

''false 

SequenceableCollection 

isClickAction 

"When used as an emphasis in a Text, do I function as 
a hyper link? I do if any of my contents does." 

''self 

detect: [:object | object isClickAction] 
transform: [ignored | true] 
ifNone: [false] 


CharacterArray 

isClickAction 

"When used as an emphasis in a Text, do I function as 
a hyper link? Strings and Symbols are never 
considered active emphases. This override keeps the 
superclass method from examining each of my 
Characters to see if they are hyper links." 

''false 

Association 

isClickAction 

"When used as an emphasis in a Text, do I function as 
a hyper link? I do if my key is #clickAction, in which 
case my value better be block-like, but I don't check 
that here." 

•^clickAction — key 

Text 

hasCIi ckAction 

"Do I contain any hyper links?" 

''runs values 

detect: [:emph | emph isClickAction] 
transform: [ignored | true] 
ifNone: [false] 

hasCIickActionAt: characterl ndex 
"Do I have a hyper link at the given 
<characterl ndex>?" 

''(self emphasisAt: characterl ndex) isClickAction 

You may notice the strange method #detect:transform:- 
ifNone:, which is like #detect:ifNone:, except that when the 
first block answers true, the value is passed through the 
second block. We discovered that we usually use the result 
of #detect: ifNone: this way, and so made it a bit easier to do: 

Collection 

detect: boolean Block transform: transformBlock ifNone: 
exceptionB lock 

"Evaluate <booleanBlock> with each of the receiver's 
elements as the argument. Pass the first element for 
which <booleanBlock> evaluates to true through 
<transformBlock> and answer the result, or answer 
the evaluation of <exceptionBlock> if no elements 
assert <booleanBlock>." 

'TransformBlock value: (self detect: booleanBlock 
ifNone: [''exceptionBlock value]) 

You should combine one or more simple presentation 
emphases with a clickAction for it to display differently, 
rather than deciding that all clickActions are going to be 
presented a particular way. We defined a simple empha¬ 
sis #1 ink as a blue underlined style, to make it familiar 
to those with Web experience. We don’t have room for 
that code today, but you'll need to make new instance 
creation methods for both CharacterAttributes and Text- 
Attributes. 
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BUT WHERE'S THE HTML? 

Once you have the foundations—a proper object model 
for hypertext—spitting out HTM L is al most trivial. We use 
a distributed responsibility pattern familiar to anyone 
who has examined how #pri ntString works: 

Object 

asHtml 

"Answer a representation of myself that is suitable for 
use in a Web page. Subclasses should not override this 
method; rather, they should override htmlOn:." 

| stream | 

stream := (String new: 100) writeStream. 
self htmlOn: stream. 

''stream contents 

Object 

htmlOn: aStream 

"Place on <aStream>a representation of myself that is 
suitable for use in a Web page. The default 
representation for objects is a #storeString 
representation in 'code' style. Answer <aStream>." 

''aStream nextPutAII: '<CODE>'; 
store: self; 

nextPutAII: '</CODE>'; 
yourself 

At this point, different objects are free to render them¬ 
selves i nto HTM L as they see fit. Of course, the one we’ve 
been concentrating on is Text, and so we have the requi¬ 
site big, ugly method. Much of this complication is be¬ 
cause ofthe desire to preserve some of the presentation of 
lines that begin with tabs. Since HTML presentation is 
normally driven by emphasis rather than content, treat¬ 
ing tabs as presentation required an awkward, double¬ 
pass treatment: 

Text 

htmlOn: aStream 

"Place on <aStream>a representation of my contents 
suitable for use in a Web page. Answer <aStream>. 

For each emphasis found, write beginning and ending 
HTML tags. 

For each special HTML Character, write the appropriate 
HTML character entity. 

For lines beginning with tabs, write the proper 
indented definition list." 

| turnOff | 

turnOff := (String new: 16) writeStream. 

''self class subscriptOutOfBoundsSignal 
handle: [:ex | 

aStream nextPutAII: turnOff contents, 
ex returnWith: aStream] 

do: [ | here tabLevel prevTabLevel thisEmphasis 
endEmph char characterEntity | 

"Handle initial tabs properly." 


Tab == self first ifTrue: [''(Text with: CR), self 
htmlOn: aStream.]. 

here : = 1. 

prevTabLevel : = tabLevel : = 0. 

"Repeat the following until I have no more data." 
[here >= self size ifTrue: [''aStream], 

"For each emphasis, build up a proper tag and an 
untag." 

thisEmphasis: = self emphasisAt: here. 
thisEmphasis class —Array ifFalse: 

[thisEmphasis : = Array with: thisEmphasis]. 

1 to: thisEmphasis size do: [:i | | emph tags | 
tags : = (emph : = thisEmphasis at: i) 
isClickAction 

ifFalse: [HtmITags at: emph ifAbsent: 
[HtmlNoTag]] 

ifTrue: [emph value asHref ->'</ A>’]. 
aStream nextPutAII: tags key. 
turnOff nextPutAII: tags value]. 

"For lines that begin with one or more tabs, build 
a proper level of indentation." 
endEmph := here + (self runLengthFor: here), 
[here <endEmph] whileTrue: 

[char: = self at: here, 
char == CR ifTrue: 

[tabLevel : = 0. 

[tabLevel : = tabLevel +1. 

Tab == (self at: here + tabLevel)] 
whileTrue: []. 
tabLevel : = tabLevel -1. 
tabLevel = prevTabLevel ifFalse: 

[char : = Tab. "to suppress <P>" 
(prevTabLevel - tabLevel) abs 
timesRepeat: 

[aStream nextPutAII: (tabLevel > 
prevTabLevel ifTrue: ['<DL>'] ifFalse: 
['</ DL>'])]]. 

tabLevel >0 ifTrue: [aStream nextPutAII: 
'<DD>']. 

prevTabLevel : = tabLevel]. 

"For each character with a given emphasis, 
write the character or its HTML-legal 
equivalent." 

characterEntity := HtmICharacterEntities at: 
char ifAbsent: []. 
characterEntity — nil 

ifTrue: [aStream nextPut: char] 
ifFalse: [aStream nextPutAII: 
characterEntity], 
here := here +1], 

aStream nextPutAII: turnOff contents. 
turnOff reset, 
here : = endEmph] repeat. 
aStream] 
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If you simply feed this method to Smalltalk, it will com¬ 
plain bitterly, because we’ve added new class variables 
to Text. We don’t like to change the definition of classes, 
but luckily, you don't need to if you’re only adding class 
variables. We have all this code in a common ENVY 
application called HyperTextBytesmiths, with a #loaded 
method that adds the needed class variables to Text on 
the fly, and of course, a #removing method that removes 
those class variables when we’re done: 

HyperTextBytesmi th s 
characterEntityTable 

"Answer a Dictionary that associates non-ASCI I 

characters with their HTML character entities." 

'IdentityDictionary new 
at: Character cr put: '<P>'; 
at: Character tab put: 
at: $" put: '&quot;'; 
at: $& put: '&amp;'; 
at: $< put: '&lt;'; 
at: $> put: '&gt;'; 
at: (Character value: 160) put 
at: (Character value: 161) put 
at: (Character value: 162) put 
at: (Character value: 163) put 
at: (Character value: 165) put 
at: (Character value: 167) put 
at: (Character value: 171) put 
at: (Character value: 176) put 
at: (Character value: 177) put 
at: (Character value: 181) put 
at: (Character value: 182) put 
at: (Character value: 183) put 
at: (Character value: 187) put 
at: (Character value: 210) put 
at: (Character value: 211) put 
at: (Character value: 225) put 
at: (Character value: 225) put 
at: (Character value: 233) put 
at: (Character value: 241) put 
at: (Character value: 249) put 
at: (Character value: 251) put 
yourself 

loaded 

"Add to TextConstants.” 

TextConstants 

at: #HtmlNoTag put: 
at: #HtmlTags put: self tagTable; 

at: #HtmlCharacterEntities put: self 
characterEntityTable 

removing 

'Take away what I added to TextConstants.” 

TextConstants 


removeKey: #HtmlNoTag ifAbsent: []; 
removeKey: #HtmlTags ifAbsent: []; 
removeKey: #HtmICharacterEntities ifAbsent: [] 

tagTable 

"Answer a Dictionary that associates a Text emphasis 
symbol with an Association of two Strings; the key is a 
tag used to turn on the emphasis, the value is used to 
turn off the emphasis.” 

IdentityDictionary new 

at: #bold put: ‘<B>'->'</B>'; 
at: Underline put: '<EM>' -> '</ EM>'; 
at: #Headingl put: '<H1>'->'</Hl>'; 
at: #Heading2 put: '<H2 >'->‘<1 H2>'; 
at: #Heading3 put: '<H3>'-> ‘<1 H3>'; 
at: #Heading4 put: ’<H4>'-> '<1 H4>'; 
at: #Heading5 put: '<H5>'->'</H5>'; 
at: #Heading6 put: '<H6>'->'</H6>'; 
at: #italic put: '<1 >'->'</1>'; 
at: #strikeout put: '<S>' -> '</ S>'; 
yourself 

Now we can generate HTML from any Text, but it is 
necessarily "embeddable" HTML only suitable for the 
"body” part of a Web page. We have numerous ways of 
producing a complete page, but the most useful way 
works from any ParagraphEditor, because it is the foun¬ 
dation text editing class in VisualWorks. (The Stream 
implementation of #htmlFor: is left as an exercise for 
the reader!) 

ParagraphEditor 

htmlOn: aStream 

"Place on aStream a representation of my contents 
suitable for use in a Web page.” 

^Stream 

nextPutAII: '<HTML><HEADxTITLE>'; 

print: sensor window label; 

nextPutAII: '</TITLEx/ HEADxBODY>'; 

htmIFor: self text; 

nextPutAII: '</ BODY></ HTML>'; cr; 

yourself 

CONCLUSION 

The Web can be a powerful communication tool, but 
like all tools, it can be misused. Just as a screw driver or 
an ice pick can kill a person, mandating inappropriate 
use of the Web can kill a project. 

We’ve demonstrated some techniques for exporting 
off-line HTML from your "hot” Smalltalk documenta¬ 
tion. Next month, we'll show you how to serve your hot 
documentation "on-line,” so that a Web browser can 
view up-to-the-minute project documentation. This 
should be enough to silence any VP who comes storm¬ 
ing in, shouting "What are you guys doing about the 
Web?” m 


cxnDsp;; 

'&iquest;'; 

'&cent;'; 

'&pound;'; 

'&yen;'; 

'&sect;'; 

'&laquo;'; 

'&deg;'; 

'&plusmn;'; 

'&micro;'; 

'&para;'; 

'&middot;'; 

'&raquo;'; 

'&reg;'; 

'&copy;'; 

'SiAEIig;'; 

'SiAEIig;'; 

'SiOslash;'; 

'&aelig;'; 

'&oslash;'; 

'Siszlia:': 
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